home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / advc11.zip / ADVC.DOC next >
Text File  |  1987-04-23  |  15KB  |  926 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                               ADVC v1.1, 04/22/87
  9.                              Advanced C Functions
  10.  
  11.                      Copyright (c) Thomas Hanlin III, 1987
  12.  
  13.           *Before June 1, 1987:                  *After June 1, 1987:
  14.           6812 Sydenstricker Rd                  1712 Maple Hill Place
  15.           Springfield, VA 22152                  Alexandria, VA 22302
  16.  
  17.  
  18.      These  routines  may  be  freely  distributed, provided that all files are
  19.  included  intact  and unmodified.  A distribution/handling fee of no more than
  20.  $10 may be charged.
  21.  
  22.      The  ADVC  routines  have been tested and appear to be bug-free.  However,
  23.  I can't guarantee as to whether they will work as advertised on your computer,
  24.  using  your  compiler.    Powerful  low-level access techniques are used which
  25.  could  conceivably  cause  havoc  on the wrong machines or wrong compilers, or
  26.  if  you  don't  use  them  properly.  Be warned, and don't use ADVC unless you
  27.  know what you're doing!
  28.  
  29.      The ADVC routines are grouped in files according to their type: Equipment,
  30.  Input,  Misc,  String,  Video.    In  order to use a routine, you will have to
  31.  extract it from the appropriate file using an editor.
  32.  
  33.      You are responsible for setting up any "include" files which may be neces-
  34.  sary for any given routine that you use in your program.
  35.  
  36.      These  routines  have been tested using Microsoft C, version 4.0.  A large
  37.  number  of  the  functions  provide  low-level  access  to  the machine, which
  38.  requires  use  of  nonportable  code.   You will have to convert these to your
  39.  compiler if you use something other than Microsoft C.
  40.  
  41.      These  routines  are  intended  as  a supplemental C library for folks who
  42.  have  some  idea  what  they're  doing.  They are not designed with the novice
  43.  in  mind.   If  you  don't  understand  how to use the functions, you probably
  44.  shouldn't attempt to use them just yet!
  45.  
  46.      If  you find the ADVC functions to be useful, your contribution to support
  47.  my  efforts  will  be  welcome.  Suggested amount, $15.  Strike a blow against
  48.  overpriced software-- support shareware!
  49.  
  50.      Notation: Routines  are  labeled  "Generic"  if they will work on with any
  51.  C  compiler  on any machine.  Routines are labeled "MS C" if they use features
  52.  specific to Microsoft C and/or the IBM PC environment.
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  Name: ANY2DEC
  75.  
  76.  Type: String / Generic
  77.  
  78.  Description:
  79.      Converts  a  number  in  string form, in any base (2-35), into an unsigned
  80.  integer.    No  checking  for  validity is done-- characters are assumed to be
  81.  within  the  proper  range  for  the base chosen, and the number as a whole is
  82.  assumed to be within unsigned integer range.
  83.  
  84.  Usage:
  85.      include <string.h>
  86.      int any2dec(str,base)
  87.          char *str;
  88.          unsigned int base;
  89.  
  90.  
  91.  
  92.  
  93.  Name: BSQUEEZE
  94.  
  95.  Type: String / Generic
  96.  
  97.  Description:
  98.      Squeezes  a  string  by  replacing  blanks  with a code sequence.  Assumes
  99.  an  input  string  which  only  uses normal ASCII (1-127) codes, with a length
  100.  of  less  than  127  characters.   Outputs a string which may include extended
  101.  ASCII  codes  (128-255).    Typical  space  savings for text is 15%.  A static
  102.  buffer  is  used,  so the result will be overwritten on subsequent calls.  See
  103.  also BUNSQUEEZE (not as bad as it sounds!).
  104.  
  105.  Usage:
  106.      unsigned char *bsqueeze(str)
  107.         unsigned char *str;
  108.  
  109.  Oddities:
  110.      May  not  be  entirely  generic,  as it assumes a useable character set of
  111.  at least 256 characters.
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  Name: BUNSQUEEZE
  141.  
  142.  Type: String / Generic
  143.  
  144.  Description:
  145.      Unsqueezes  a  string  which was squeezed with BSQUEEZE.  Assumes an input
  146.  string  with  a  length of less than 127 characters.  A static buffer is used,
  147.  so the result will be overwritten on subsequent calls.
  148.  
  149.  Usage:
  150.      unsigned char *bunsqueeze(str)
  151.         unsigned char *str;
  152.  
  153.  Oddities:
  154.      May  not  be  entirely  generic,  as  it  assumes  a useable character set
  155.  comprised of 256 characters.
  156.  
  157.  
  158.  
  159.  
  160.  Name: BKSCROLL
  161.  
  162.  Type: Video / MS C
  163.  
  164.  Description:
  165.      Scrolls  an  area  of  the  screen down by a specified number of lines, or
  166.  clears  it entirely if you specify zero lines.  The screen area to be scrolled
  167.  is defined by its upper left and lower right corners.
  168.  
  169.  Usage:
  170.      #include <dos.h>
  171.      void bkscroll(leftcol,toprow,rightcol,bottomrow,lines)
  172.          int leftcol, toprow, rightcol, bottomrow, lines;
  173.  
  174.  Oddities:
  175.      Uses the BIOS video interrupts.
  176.  
  177.  
  178.  
  179.  
  180.  Name: CLREOL
  181.  
  182.  Type: Video / MS C
  183.  
  184.  Description:
  185.      Clears from the current cursor position to the end of line.
  186.  
  187.  Usage:
  188.       #include <dos.h>
  189.       void clreol()
  190.  
  191.  Oddities:
  192.      Uses the BIOS video interrupts.
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  Name: COMMPORTS
  207.  
  208.  Type: Equipment / MS C
  209.  
  210.  Description:
  211.      Returns the number of communications (serial) ports that are installed.
  212.  
  213.  Usage:
  214.      #include <dos.h>
  215.      int commports()
  216.  
  217.  Oddities:
  218.      Uses a BIOS interrupt.
  219.  
  220.  
  221.  
  222.  
  223.  Name: DEC2ANY
  224.  
  225.  Type: String / Generic
  226.  
  227.  Description:
  228.      This  function  converts  an  unsigned integer into an ASCII string in the
  229.  base  of  your  choice  (2-35).    It uses a static buffer, so the result will
  230.  be overwritten on subsequent calls.
  231.  
  232.  Usage:
  233.       char *dec2any(number,base)
  234.          unsigned int number, base;
  235.  
  236.  
  237.  
  238.  
  239.  Name: DELAY
  240.  
  241.  Type: Miscellaneous / MS C
  242.  
  243.  Description:
  244.      Delays for a given number of seconds.
  245.  
  246.  Usage:
  247.       #include <stddef.h>
  248.       #include <time.h>
  249.       void delay(seconds)
  250.          unsigned int seconds;
  251.  
  252.  Oddities:
  253.      Uses  a  time  function  specific to Microsoft C, which returns the GMT as
  254.  a number of seconds.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  Name: DISPLAYTYPE
  273.  
  274.  Type: Video / MS C
  275.  
  276.  Description:
  277.      Returns the type of the current display: 0 = mono, 1 = color.
  278.  
  279.  Usage:
  280.      #include <dos.h>
  281.      int displaytype()
  282.  
  283.  Oddities:
  284.      Uses a BIOS video interrupt.
  285.  
  286.  
  287.  
  288.  
  289.  Name: DRIVESPACE
  290.  
  291.  Type: Equipment / MS C
  292.  
  293.  Description:
  294.      Returns  the  amount  of  free space left on a given disk drive, in bytes.
  295.  Specify the drive by its letter, or use '@' for the default drive.
  296.  
  297.  Usage:
  298.      #include <ctype.h>
  299.      #include <dos.h>
  300.  
  301.  Oddities:
  302.      Uses a DOS interrupt.
  303.  
  304.  
  305.  
  306.  
  307.  Name: EXTRACT
  308.  
  309.  Type: String / Generic
  310.  
  311.  Description:
  312.      Extracts  a  delimited  substring  from a string.  Substrings are numbered
  313.  starting at one, and may not be over 80 characters in length.  A static buffer
  314.  is used for the substring, so save results if need be before the next use.
  315.  
  316.  Example usage:
  317.      extract("John Doe=1919 Main St=Springfield IL 12345",'=',2)
  318.  would  return  the  second  substring  delimited  by an equal sign, or in this
  319.  case "1919 Main St".
  320.  
  321.  Usage:
  322.       char *extract(str,delimiter,elementnumber)
  323.          char *str, delimiter;
  324.          int elementnumber;
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  Name: GETDRIVE
  339.  
  340.  Type: Equipment / MS C
  341.  
  342.  Description:
  343.      Returns the current default disk drive.
  344.  
  345.  Usage:
  346.       #include <dos.h>
  347.       char getdrive()
  348.  
  349.  Oddities:
  350.      Uses a DOS interrupt.
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  Name: GETKEY
  405.  
  406.  Type: Input / MS C
  407.  
  408.  Description:
  409.      Waits  for  one  of  a list of keys to be pressed, and returns the pressed
  410.  key.    The  list  of  valid  keys must be in uppercase; the returned key will
  411.  always  be  converted  to  uppercase.  If the list of valid keys is null, then
  412.  the first key pressed will be returned.
  413.  
  414.  Usage:
  415.       #include <conio.h>
  416.       #include <ctype.h>
  417.       char getkey(str)
  418.          char *str;
  419.  
  420.  Oddities:
  421.      Uses  unbuffered  input  to  get  a  key as soon as it's pressed.  This is
  422.  a common but nonstandard function.
  423.  
  424.  
  425.  
  426.  
  427.  Name: JOYSTICK
  428.  
  429.  Type: Equipment / MS C
  430.  
  431.  Description:
  432.      Returns the number of joystick ports installed (0-1).
  433.  
  434.  Usage:
  435.       #include <dos.h>
  436.       int joystick()
  437.  
  438.  Oddities:
  439.      Uses a